home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_HDF.idb / usr / freeware / include / hdf / mfan.h.z / mfan.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  14.4 KB  |  373 lines
  1. /****************************************************************************
  2.  * NCSA HDF                                                                 *
  3.  * Software Development Group                                               *
  4.  * National Center for Supercomputing Applications                          *
  5.  * University of Illinois at Urbana-Champaign                               *
  6.  * 605 E. Springfield, Champaign IL 61820                                   *
  7.  *                                                                          *
  8.  * For conditions of distribution and use, see the accompanying             *
  9.  * hdf/COPYING file.                                                        *
  10.  *                                                                          *
  11.  ****************************************************************************/
  12.  
  13. /* $Id: mfan.h,v 1.15 1997/10/21 17:45:06 georgev Exp $ */
  14.  
  15. /*------------------------------------------------------------------------------
  16.  * File:    mfan.h
  17.  * Author:  GeorgeV
  18.  * Purpose: header file for the Multi-file Annotation Interface
  19.  * Invokes: 
  20.  * Contents:
  21.  *          Structure definitions: ANnode, ANentry
  22.  *          Constant definitions:  AN_DATA_LABEL, AN_DATA_DESC
  23.  *          (-moved to hdf.h)      AN_FILE_LABEL, AN_FILE_DESC
  24.  *
  25.  *----------------------------------------------------------------------------*/
  26.  
  27. #ifndef _MFAN_H  /* avoid re-inclusion */
  28. #define _MFAN_H
  29.  
  30. #include "hdf.h"
  31.  
  32. #if 0
  33. /* enumerated types of the varous annotation types 
  34.  * NOTE: moved to hdf.h since they are used by end users. */
  35. typedef enum 
  36. { 
  37.   AN_DATA_LABEL = 0, /* Data label */
  38.   AN_DATA_DESC,      /* Data description */
  39.   AN_FILE_LABEL,     /* File label */
  40.   AN_FILE_DESC       /* File description */
  41. } ann_type;
  42. #endif
  43.  
  44. #ifdef MFAN_C
  45. /* WE ARE IN MAIN ANNOTATION SOURCE FILE "mfan.c" */
  46.  
  47. /* PRIVATE variables and definitions */
  48.  
  49. /* This sturcture is used to find which file the annotation belongs to
  50.  * and use the subsequent file specific annotation 'key' to find the 
  51.  * annotation. The annotation atom group(ANIDGROUP) keeps track of 
  52.  * all anotations across the file. */
  53. typedef struct ANnode
  54. {
  55.   int32   file_id;  /* which file this annotation belongs to */
  56.   int32   ann_key;  /* type/ref: used to find annotation in corresponding
  57.                        TBBT in filerec_t->tree[]. */
  58.   intn    new_ann;  /* flag */
  59. } ANnode;
  60.  
  61. /*
  62.  * This structure is an entry in the label/desc tree
  63.  * for a label/desc in the file, it gives the ref of the label/desc,
  64.  * and the tag/ref of the data item to which the label/desc relates 
  65.  * The filerec_t->an_tree[] TBBT members will contain these entries.
  66.  **/
  67. typedef struct ANentry
  68. {
  69.   int32   ann_id;      /* annotation id */
  70.   uint16  annref;      /* ref of annotation */
  71.   uint16  elmtag;      /* tag of data */
  72.   uint16  elmref;      /* ref of data */
  73. } ANentry;
  74.  
  75.  
  76. /* This is the size of the hash tables used for annotation IDs */
  77. #define ANATOM_HASH_SIZE    64
  78.  
  79. /* Used to create unique 32bit keys from annotation type and reference number 
  80.  *  This key is used to add nodes to a corresponding TBBT in 
  81.  *  filrerec_t->an_tree[]. 
  82.  *  ----------------------------
  83.  *  | type(16bits) | ref(16bits) |
  84.  *  -----------------------------*/
  85. #define AN_CREATE_KEY(t,r) ((((int32)t & 0xffff) << 16) | r)
  86.  
  87. /* Obtain Reference number from key */
  88. #define AN_KEY2REF(k)      ((uint16)((int32)k & 0xffff))
  89.  
  90. /* Obtain Annotation type from key */
  91. #define AN_KEY2TYPE(k)     ((int32)((int32)k >> 16))
  92.  
  93. #else /* !MFAN_C */
  94. /* WE are NOT in main ANNOTATION source file
  95.  * Nothing EXPORTED except Public fcns */
  96.  
  97.  
  98. /******************************************************************************
  99.  NAME
  100.     ANdestroy -- Un-Initialize Annotation Interface
  101.  
  102.  DESCRIPTION
  103.     Unallocates global annotaton node list and file list.
  104.  
  105.  RETURNS
  106.     SUCCEED or FAIL
  107. *******************************************************************************/
  108. extern intn ANdestroy(void);
  109.  
  110. /******************************************************************************
  111.  NAME
  112.    ANstart - open file for annotation handling
  113.  
  114.  DESCRIPTION
  115.    Start annotation handling on the file return a annotation ID to the file.
  116.  
  117.  RETURNS
  118.    A file ID or FAIL.
  119. *******************************************************************************/
  120. extern int32 ANstart(int32 file_id /* IN: file to start annotation access on */);
  121.  
  122. /******************************************************************************
  123.  NAME
  124.    ANfileinfo - Report high-level information about the ANxxx interface for a given file.
  125.  
  126.  DESCRIPTION
  127.    Reports general information about the number of file and object(i.e. data)
  128.    annotations in the file. This routine is generally used to find
  129.    the range of acceptable indices for ANselect calls.
  130.  
  131.  RETURNS
  132.    Returns SUCCEED if successful and FAIL othewise
  133.  
  134. *******************************************************************************/
  135. extern intn  ANfileinfo(int32 an_id,         /* IN:  annotation interface id */
  136.                         int32 *n_file_label, /* OUT: the # of file labels */
  137.                         int32 *n_file_desc,  /* OUT: the # of file descriptions */
  138.                         int32 *n_obj_label,  /* OUT: the # of object labels */ 
  139.                         int32 *n_obj_desc    /* OUT: the # of object descriptions */);
  140.  
  141. /******************************************************************************
  142.  NAME
  143.    ANend - End annotation access to file file
  144.  
  145.  DESCRIPTION
  146.    End annotation access to file.
  147.  
  148.  RETURNS
  149.    SUCCEED if successful and  FAIL otherwise.
  150. *******************************************************************************/
  151. extern int32 ANend(int32 an_id /* IN: Annotation ID of file to close */);
  152.  
  153. /******************************************************************************
  154.  NAME
  155.    ANcreate - create a new element annotation and return a handle(id)
  156.  
  157.  DESCRIPTION
  158.    Creates a data annotation, returns an 'an_id' to work with the new 
  159.    annotation which can either be a label or description.
  160.    Valid annotation types are AN_DATA_LABEL for data labels and 
  161.    AN_DATA_DESC for data descriptions.
  162.  
  163.  RETURNS
  164.         An ID to an annotation which can either be a label or description.
  165. *******************************************************************************/
  166. extern int32 ANcreate(int32 an_id,     /* IN: annotation interface ID */
  167.                       uint16 elem_tag, /* IN: tag of item to be assigned annotation */
  168.                       uint16 elem_ref, /* IN: reference number of itme to be assigned ann*/
  169.                       ann_type type    /* IN: annotation type */);
  170.  
  171.  
  172. /******************************************************************************
  173.  NAME
  174.     ANcreatef - create a new file annotation and return a handle(id)
  175.  
  176.  DESCRIPTION
  177.     Creates a file annotation, returns an 'an_id' to work with the new 
  178.     file annotation which can either be a label or description.
  179.     Valid annotation types are AN_FILE_LABEL for file labels and
  180.     AN_FILE_DESC for file descritpions.
  181.  
  182.  RETURNS
  183.         An ID to an annotation which can either be a file label or description
  184. *******************************************************************************/
  185. extern int32 ANcreatef(int32 an_id,  /* IN: annotation interface ID */
  186.                        ann_type type /* IN:  annotation type */);
  187.  
  188. /******************************************************************************
  189.  NAME
  190.     ANselect - get an annotation ID from index of 'type'
  191.  
  192.  DESCRIPTION
  193.     Get an annotation Id from index of 'type'.
  194.     The position index is ZERO based
  195.  
  196.  RETURNS
  197.     An ID to an annotation type which can either be a label or description 
  198. *******************************************************************************/
  199. extern int32 ANselect(int32 an_id,  /* IN: annotation interface ID */
  200.                       int32 index,  /* IN: index of annottion to get ID for */
  201.                       ann_type type /* IN: annotation type */);
  202.  
  203. /******************************************************************************
  204.  NAME
  205.    ANnumann - find number of annotation of 'type' that  match the given element tag/ref 
  206.  
  207.  DESCRIPTION
  208.    Find number of annotation of 'type' for the given element 
  209.    tag/ref pair.Should not be used for File labels and
  210.    descriptions.
  211.  
  212.  RETURNS
  213.    number of annotation found if successful and FAIL (-1) otherwise
  214.  
  215. *******************************************************************************/
  216. extern intn  ANnumann(int32 an_id,     /* IN: annotation interface id */
  217.                       ann_type type,   /* IN: annotation type */
  218.                       uint16 elem_tag, /* IN: tag of item of which this is annotation */
  219.                       uint16 elem_ref  /* IN: ref of item of which this is annotation*/);
  220.  
  221. /******************************************************************************
  222.  NAME
  223.    ANannlist - generate list of annotation ids of 'type' that match the given element tag/ref 
  224.  
  225.  DESCRIPTION
  226.    Find and generate list of annotation ids of 'type' for the given 
  227.    element tag/ref pair.Should not be used for File labels and
  228.    descriptions.
  229.  
  230.  RETURNS
  231.    number of annotations ids found if successful and FAIL (-1) otherwise
  232.  
  233. *******************************************************************************/
  234. extern intn  ANannlist(int32 an_id,     /* IN: annotation interface id */
  235.                        ann_type type,   /* IN: annotation type */
  236.                        uint16 elem_tag, /* IN: tag of item of which this is annotation */
  237.                        uint16 elem_ref, /* IN: ref of item of which this is annotation*/
  238.                        int32 ann_list[] /* OUT: array of ann_id's that match criteria.*/);
  239.  
  240. /******************************************************************************
  241.  NAME
  242.    ANannlen - get length of annotation givne annotation id
  243.  
  244.  DESCRIPTION
  245.    Uses the annotation id to find ann_key & file_id
  246.  
  247.  RETURNS
  248.    length of annotation if successful and FAIL (-1) otherwise
  249.  
  250. *******************************************************************************/
  251. extern int32 ANannlen(int32 ann_id /* IN: annotation id */);
  252.  
  253. /******************************************************************************
  254.  NAME
  255.    ANwriteann - write annotation given ann_id
  256.  
  257.  DESCRIPTION
  258.    Checks for pre-existence of given annotation, replacing old one if it
  259.    exists. Writes out annotation.
  260.  
  261.  RETURNS
  262.    SUCCEED (0) if successful and FAIL (-1) otherwise
  263.  
  264. *******************************************************************************/
  265. extern int32 ANwriteann(int32 ann_id,    /* IN: annotation id */
  266.                         const char *ann, /* IN: annotation to write */
  267.                         int32 annlen     /* IN: length of annotation*/);
  268.  
  269. /******************************************************************************
  270.  NAME
  271.    ANreadann - read annotation given ann_id
  272.  
  273.  DESCRIPTION
  274.    Gets tag and ref of annotation.  Finds DD for that annotation.
  275.    Reads the annotation, taking care of NULL terminator, if necessary.
  276.  
  277.  RETURNS
  278.    SUCCEED (0) if successful and FAIL (-1) otherwise
  279.  
  280. *******************************************************************************/
  281. extern int32 ANreadann(int32 ann_id, /* IN: annotation id (handle) */
  282.                        char *ann,    /* OUT: space to return annotation in */
  283.                        int32 maxlen  /* IN: size of space to return annotation in */);
  284.  
  285. /******************************************************************************
  286.  NAME
  287.     ANendaccess - end access to an annotation given it's id
  288.  
  289.  DESCRIPTION
  290.     Terminates access to an annotation. For now does nothing
  291.  
  292.  RETURNS
  293.     SUCCEED(0) or FAIL(-1)
  294. *******************************************************************************/
  295. extern intn  ANendaccess(int32 ann_id /* IN: annotation id */);
  296.  
  297. /******************************************************************************
  298.  NAME
  299.    ANget_tagref - get tag/ref pair for annotation based on type and index
  300.  
  301.  DESCRIPTION
  302.    Get the tag/ref of the annotation based on  the type and index of the 
  303.    annotation. The position index is zero based
  304.  
  305.  RETURNS
  306.    A tag/ref pairt to an annotation type which can either be a 
  307.    label or description.
  308.  
  309. *******************************************************************************/
  310. extern int32 ANget_tagref(int32 an_id,    /* IN: annotation interface ID */
  311.                           int32 index,    /* IN: index of annotation to get tag/ref for*/
  312.                           ann_type type,  /* IN: annotation type */
  313.                           uint16 *ann_tag,/* OUT: Tag for annotation */ 
  314.                           uint16 *ann_ref /* OUT: ref for annotation */);
  315.  
  316. /******************************************************************************
  317.  NAME
  318.    ANid2tagref -- get tag/ref given annotation id
  319.  
  320.  DESCRIPTION
  321.    Uses the annotation id to find ann_node entry which contains ann_ref
  322.  
  323.  RETURNS
  324.    SUCCEED(0) if successful and FAIL (-1) otherwise. 
  325. *******************************************************************************/
  326. extern int32 ANid2tagref(int32 ann_id,    /* IN: annotation id */
  327.                          uint16 *ann_tag, /* OUT: Tag for annotation */
  328.                          uint16 *ann_ref  /* OUT: ref for annotation */);
  329.  
  330. /******************************************************************************
  331.  NAME
  332.    ANtagref2id -- get annotation id given tag/ref
  333.  
  334.  DESCRIPTION
  335.    Gets the annotation id of the annotation given the tag/ref of
  336.    the annotation itself and the annotation interface id.
  337.  
  338.  RETURNS
  339.    Annotation id of annotation if successful and FAIL(-1) otherwise. 
  340. *******************************************************************************/
  341. extern int32 ANtagref2id(int32 an_id,    /* IN  Annotation interface id */
  342.                          uint16 ann_tag, /* IN: Tag for annotation */
  343.                          uint16 ann_ref  /* IN: ref for annotation */);
  344.  
  345. /******************************************************************************
  346.  NAME
  347.    ANatype2tag - annotation type to corresponding annotation TAG
  348.  
  349.  DESCRIPTION
  350.    Translate annotation type to corresponding TAG.
  351.  
  352.  RETURNS
  353.    Returns TAG corresponding to annotatin type.
  354. *******************************************************************************/
  355. extern uint16 ANatype2tag(ann_type atype /* IN: Annotation type */);
  356.  
  357. /******************************************************************************
  358.  NAME
  359.    ANtag2atype - annotation TAG to corresponding annotation type
  360.  
  361.  DESCRIPTION
  362.    Translate annotation TAG to corresponding atype
  363.  
  364.  RETURNS
  365.    Returns type corresponding to annotatin TAG.
  366. *******************************************************************************/
  367. extern ann_type ANtag2atype(uint16 atag /* IN: annotation tag */);
  368.  
  369.  
  370. #endif /* !MFAN_C */
  371.  
  372. #endif /* _MFAN_H */
  373.